Projects

Projects are the top-level organizational container for a BindAI solution. A Project groups applications, shared tools, workflows, scheduling, and project-level configuration. It also exposes placeholders for project-wide knowledge, memories, and secrets. Projects are provided by the bindai-project package.

What a Project Contains

A BindAI project currently provides these resources:

Applications
Shared tools
Workflows
Workflow scheduling
Project configuration
Project-level knowledge storage placeholder
Project-level memory storage placeholder
Project-level secrets storage placeholder

The project acts as a convenient root object for composing these resources. A project does not currently provide a complete database-backed resource-management system. Some project-level collections, such as knowledge, memories, and secrets, are currently generic dictionaries intended as extension points.

Project Configuration

Every Project is created with a ProjectConfiguration.

from bindai_project import Project, ProjectConfiguration

config = ProjectConfiguration(
    name="my-project",
    version="1.0.0",
    description="My BindAI project",
)

project = Project(config)

The configuration contains:

Field	Type	Default	Description
`name`	`str`	required	Project name
`version`	`str`	`"1.0.0"`	Project version
`description`	`str`	`""`	Project description

ProjectConfiguration is a dataclass using slots. The project name is exposed through:

project.name

which returns project.configuration.name.

Applications

Applications are the main execution containers inside a project. A project stores applications by name:

project.add_application(application)

Applications can then be retrieved by name:

application = project.application("my-app")

Adding an application with an existing name replaces the previous entry. Example:

from bindai_project import Project, ProjectConfiguration

project = Project(
    ProjectConfiguration(name="customer-support")
)

project.add_application(application)

result = project.run(
    application="my-app",
    agent="support-agent",
    message="Help me with my account.",
)

Applications remain responsible for their own agents and application-level execution behavior. The project provides the higher-level container and lookup mechanism.

Shared Tools

Projects contain a shared ToolRegistry. Tools can be registered at project level:

project.add_tool(tool)

This allows tools to be shared by applications or workflows where the application configuration makes use of them. The project delegates registration to its internal ToolRegistry. The Project API does not define a separate tool implementation system; it provides a convenient project-level registry.

Workflows

Projects contain a WorkflowRegistry. Workflows can be registered with:

project.add_workflow(workflow)

and retrieved by workflow ID:

workflow = project.workflow("my-workflow")

The project also creates a WorkflowScheduler:

project.scheduler

Schedules can be added through:

project.add_schedule(schedule)

The workflow itself remains responsible for its execution logic. The project provides the registry and scheduling container.

Scheduling

Project scheduling is currently backed by WorkflowScheduler. A schedule can be registered through:

project.add_schedule(schedule)

or accessed through:

project.scheduler

Scheduling should be understood separately from the bindai-automation worker system. The Project package provides workflow scheduling primitives, while the Automation package provides automation definitions, triggers, background execution, state, and run history.

Knowledge

Projects expose a project-level knowledge collection:

project.knowledge

The current implementation initializes this as:

dict[str, object]

It is therefore currently a generic project-level storage container rather than a complete knowledge-management subsystem. For production retrieval, embeddings, vector databases, document ingestion, and RAG behavior, use BindAI’s knowledge and retrieval components rather than assuming that Project.knowledge provides those capabilities automatically.

Memories

Projects also expose:

project.memories

The current implementation initializes this as:

dict[str, object]

This is a project-level extension point. It should not be confused with the framework’s agent memory capabilities. Agent memory is part of agent execution and context management, while Project.memories is currently only a generic project-owned collection.

Secrets

Projects expose:

project.secrets

which is currently initialized as:

dict[str, object]

This provides a project-level place for application-specific secret references or configuration data. For actual deployments, avoid placing plaintext credentials directly into source code or committed project files. Use environment variables or an appropriate secret-management system for sensitive credentials.

Project Execution

A project provides convenience methods for executing an agent through a named application.

Run

result = project.run(
    application="my-app",
    agent="assistant",
    message="Hello!",
)

The project:

Looks up the application by name.
Calls the application’s run() method.
Returns the application’s result.

Stream

Streaming is available through:

stream = project.stream(
    application="my-app",
    agent="assistant",
    message="Tell me a story.",
)

The project delegates to the selected application’s stream() method. The exact streaming behavior therefore depends on the application’s implementation.

Python Helpers

Project provides several convenience methods for working with its applications.

Membership

if "my-app" in project:
    ...

This checks whether an application with the given name exists.

Length

len(project)

returns the number of registered applications.

Iteration

for application in project:
    ...

iterates over the project’s registered application objects.

Typical Project Structure

A project can be composed like this:

from bindai_project import Project, ProjectConfiguration

project = Project(
    ProjectConfiguration(
        name="customer-support",
        version="1.0.0",
        description="Customer support AI system",
    )
)

project.add_application(application)
project.add_tool(shared_tool)
project.add_workflow(workflow)
project.add_schedule(schedule)

The project then provides a single root object through which these resources can be accessed.

Projects and Applications

Projects and applications have different responsibilities.

Project

The project provides:

project identity
application registration
shared tool registry
workflow registry
workflow scheduler
project-level configuration
project-level extension collections
application execution helpers

Application

An application provides the actual application runtime and its configured agents and execution behavior. This separation allows a project to contain multiple applications:

Project
├── Application: customer-support
├── Application: research
├── Application: content
├── Shared Tools
├── Workflows
└── Scheduler

Multiple Applications

A project can contain multiple applications:

project.add_application(support_app)
project.add_application(research_app)
project.add_application(content_app)

They are stored by their application names. Execution can then target a specific application:

project.run(
    application="research",
    agent="researcher",
    message="Research this topic.",
)

This makes the project useful as a top-level container for related applications.

Workflows and Applications

Projects can contain both applications and workflows. They serve different purposes:

Project
│
├── Applications
│   ├── Support App
│   └── Research App
│
├── Shared Tools
│
├── Workflows
│   ├── Research Workflow
│   └── Approval Workflow
│
└── Scheduler

Applications are execution containers for configured agents. Workflows provide structured multi-step execution. The project groups both under one project-level configuration.

Connections

External service integrations are provided by the bindai-connections package rather than being implemented directly by Project. Current BindAI connection types include:

Webhook
GitHub
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify
Google Sheets
Google Docs
Gmail
Google Drive

Connections can be managed independently and then used by applications, tools, workflows, or other application-level components as appropriate. The project itself does not currently maintain a dedicated connection registry.

The project provides a natural scope for resources that should be shared across applications. For example:

Project
│
├── Shared Tools
│
├── Application A
│   └── Agents
│
├── Application B
│   └── Agents
│
└── Workflows

Shared tools are explicitly represented by the project’s ToolRegistry. Applications retain their own application-level configuration and runtime state.

Isolation

Applications are stored independently by name:

project.applications

A project does not automatically merge the internal agent registries, memories, or other runtime state of its applications. Resource sharing should therefore be explicit. For example, registering a tool at the project level does not by itself imply that every application automatically uses that tool.

Project API

The current public Project API includes:

Project(configuration)

Properties

project.configuration
project.name
project.applications
project.tools
project.workflows
project.scheduler
project.knowledge
project.memories
project.secrets

Application methods

project.add_application(application)
project.application(name)

Tool methods

project.add_tool(tool)

Workflow methods

project.add_workflow(workflow)
project.workflow(workflow_id)

Scheduling

project.add_schedule(schedule)

Execution

project.run(
    application=...,
    agent=...,
    message=...,
)

project.stream(
    application=...,
    agent=...,
    message=...,
)

Python helpers

name in project
len(project)

for application in project:
    ...

Project Package

Projects are provided by the bindai-project package. The package currently contains the core project components:

bindai-project/
├── src/
│   └── bindai_project/
│       ├── project.py
│       ├── configuration.py
│       ├── builder.py
│       ├── registry.py
│       └── __init__.py
└── tests/

The Project package depends on BindAI’s application, core tool, and workflow components.

Projects in the REST API

The BindAI REST API exposes configured projects through:

GET /api/v1/projects
GET /api/v1/projects/{project_name}

Projects must first be configured in the API application:

from bindai_api import configure_project

configure_project(project)

The API does not automatically discover every Project object in the Python process. The REST API therefore acts as an interface to explicitly configured projects.

Docker and Deployment

Projects can be used in normal Python deployments as well as through the BindAI API Docker image. For API deployment, see:

The current API deployment model uses an in-process application and worker model. Distributed project execution, durable queues, and Kubernetes deployment are future infrastructure concerns and are not required for the current v0.1 project model.

Recommended Usage

Use Project when you need a clear top-level container for related BindAI applications and shared resources. A typical composition is:

Project
│
├── Configuration
│
├── Applications
│   ├── Agents
│   ├── Memory
│   └── Tools
│
├── Shared Tools
│
├── Workflows
│
├── Workflow Scheduler
│
├── Knowledge collection
├── Memory collection
└── Secrets collection

Keep application-specific behavior inside the application. Use project-level resources for genuinely shared concerns.

Current Scope

The current Project implementation is intentionally lightweight. It provides:

project configuration
application registration
shared tools
workflow registration
workflow scheduling
project-level extension collections
application execution helpers

It does not currently provide:

a persistent project database
a project-level ORM
automatic resource discovery
a built-in secret manager
a built-in knowledge database
a built-in project memory database
automatic connection management
distributed execution
queue-backed project workers
multi-tenant project isolation
project-level authentication or authorization

These capabilities can be layered around the project model as the BindAI ecosystem evolves.

Current v0.1 Role

For BindAI v0.1, Project should be viewed as the top-level Python composition container for related applications and shared workflow resources. The project model is useful for:

organizing multiple applications
registering shared tools
grouping workflows
managing workflow schedules
providing project identity and configuration
exposing a clean root object for application execution
integrating projects with the BindAI REST API

More advanced project management capabilities can be added later without changing the basic role of the project as the root container.

​Projects

​What a Project Contains

​Project Configuration

​Applications

​Shared Tools

​Workflows

​Scheduling

​Knowledge

​Memories

​Secrets

​Project Execution

​Run

​Stream

​Python Helpers

​Membership

​Length

​Iteration

​Typical Project Structure

​Projects and Applications

​Project

​Application

​Multiple Applications

​Workflows and Applications

​Connections

​Project-Level Resource Sharing

​Isolation

​Project API

​Properties

​Application methods

​Tool methods

​Workflow methods

​Scheduling

​Execution

​Python helpers

​Project Package

​Projects in the REST API

​Docker and Deployment

​Recommended Usage

​Current Scope

​Current v0.1 Role

Projects

What a Project Contains

Project Configuration

Applications

Shared Tools

Workflows

Scheduling

Knowledge

Memories

Secrets

Project Execution

Run

Stream

Python Helpers

Membership

Length

Iteration

Typical Project Structure

Projects and Applications

Project

Application

Multiple Applications

Workflows and Applications

Connections

Project-Level Resource Sharing

Isolation

Project API

Properties

Application methods

Tool methods

Workflow methods

Scheduling

Execution

Python helpers

Project Package

Projects in the REST API

Docker and Deployment

Recommended Usage

Current Scope

Current v0.1 Role